Contents | Prev | Next | Java Core Reflection |
Field
, Method
, and
Constructor
-that reflect class and interface members
and constructors. These classes provide:Class
that provide for the
construction of new instances of the Field
,
Method
, and Constructor
classes.Array
provides methods to dynamically
construct and access Java arrays.Modifier
helps decode Java
language modifier information about classes and their
members.InvocationTargetException
is used to
wrap exceptions thrown by reflected methods or constructors.AccessibleObject
and
ReflectPermission
-that provide a mechanism to suppress
standard Java language access control.java.lang
package that support reflection. These are:
Class
. These represent the primitive Java types
boolean
, byte
, char
,
short
, int
, long
,
float
, and double
, and the keyword
void
, at run-time.Void
-to hold a
reference to the Class
object representing the keyword
void
. One category is comprised of applications
that need to discover and use all of the public
members of a target object based on its run-time class. These
applications require run-time access to all the public
fields, methods, and constructors of an object. Examples in this
category are services such as Java(TM) Beans[1], and lightweight tools, such as
object inspectors. These applications use the instances of the
classes Field
, Method
, and
Constructor
obtained through the methods
getField
, getMethod
,
getConstructor
, getFields
,
getMethods
, and getConstructors
of class
Class
.
The second category consists of
sophisticated applications that need to discover and use the
members declared by a given class. These applications need run-time
access to the implementation of a class at the level provided by a
class
file. Examples in this category are development
tools, such as interpreters, inspectors, and class browsers, and
run-time services, such as Java(TM) Object
Serialization[2]. These
applications use instances of the classes Field
,
Method
, and Constructor
obtained through
the methods getDeclaredField
,
getDeclaredMethod
,
getDeclaredConstructor
,
getDeclaredFields
, getDeclaredMethods
,
and getDeclaredConstructors
of class
Class
.
Field
,
Method
, and Constructor
are
final
. Only the Java Virtual Machine may create
instances of these classes; these objects are used to manipulate
the underlying objects; that is, to:
final
uninstantiable class
Array
provides static
methods that permit
creating new arrays, and getting and setting the elements of
arrays.
Field
,
Method
and Constructor
implement the
Member
interface. The methods of Member
are used to query a reflected member for basic identifying
information. Identifying information consists of the class or
interface that declared the member, the name of the member itself,
and the Java language modifiers (such as public
,
protected
, abstract
,
synchronized
, and so on) for the member.
Field
object represents a
reflected field. The underlying field may be a class variable (a
static
field) or an instance variable (a
non-static
field). Methods of class Field
are used to obtain the type of the underlying field, and to get and
set the underlying field's value on objects.
Method
object represents a
reflected method. The underlying method may be an abstract method,
an instance method, or a class (static
) method.
Methods of class Method
are
used to obtain the formal parameter types, the return type, and the
checked exception types of the underlying method. In addition, the
invoke
method of class Method
is used to
invoke the underlying method on target objects. Instance and
abstract method invocation uses dynamic method resolution based on
the target object's run-time class and the reflected method's
declaring class, name, and formal parameter types. (Thus, it is
permissible to invoke a reflected interface method on an object
that is an instance of a class that implements the interface.)
Static method invocation uses the underlying static method of the
method's declaring class.
Constructor
object represents a
reflected constructor. Methods of class Constructor
are used to obtain the formal parameter types and the checked
exception types of the underlying constructor. In addition, the
newInstance
method of class Constructor
is used to create and initialize a new instance of the class that
declares the constructor, provided the class is instantiable.
Array
class is an
uninstantiable class that exports class methods to create Java
arrays with primitive or class component types. Methods of class
Array
are also used to get and set array component
values.
The Modifier
class is an
uninstantiable class that exports class methods to decode Java
language modifiers for classes and members. The language modifiers
are encoded in an integer, and use the encoding constants defined
by The Java Virtual Machine Specification.
Class
objects that are used to represent the eight primitive Java types
and void
at run-time. (Note that these are
Class
objects, not classes.) The Core
Reflection API uses these objects to identify the following:
Class
objects. They have the same names as the types
that they represent. The Class
objects may only be
referenced via the following public
final
static
variables:
java.lang.Boolean.TYPE java.lang.Character.TYPE java.lang.Byte.TYPE java.lang.Short.TYPE java.lang.Integer.TYPE java.lang.Long.TYPE java.lang.Float.TYPE java.lang.Double.TYPE java.lang.Void.TYPEIn particular, these
Class
objects
are not accessible via the forName
method of class
Class
.
Class
that give reflective
access to a member or a set of members of a class are the only
source for instances of Field
, Method
,
and Constructor
. These methods first delegate security
checking to the system security manager (if installed), which
throws a SecurityException
should the request for
reflective access be denied.protected
, default (package)
access, and private
classes and members-will normally
occur when the individual reflected members are used to operate on
the underlying members of objects,that is, to get or set field
values, to invoke methods, or to create and initialize new objects.
Unrestricted access, which overrides standard language access
control rules, may be granted to privileged code using the
setAccessible
method. This method is inherited from
AccessibleObject
by the classes Field
,
Method
, and Constructor
.SecurityManager
: void checkMemberAccess(Class,int) throws
SecurityException
The Class
parameter of
checkMemberAccess
identifies the class or interface
whose members need to be accessed. The int
parameter
identifies the set of members to be accessed-either
Member.PUBLIC
or Member.DECLARED
.
void checkPackageAccess(String pkg)
throws SecurityException
java.lang.RuntimePermission
that affect these
policies. These are:
accessDeclaredMembers.
This grants the ability to
reflect on non-public members of classes.accessClassInPackage{package name}.
This grants
access to classes in the specified package. These permissions are
determined by the security manager.SecurityException
. If the requested access to the set
is granted, the method should return.
As stated earler, standard Java language access control will usually be enforced when a reflected member from this set is used to operate on an underlying object, that is, when:
Field
is used to get or set a field valueMethod
is used to invoke a methodConstructor
is used to create and initialize a
new instance of a classIllegalAccessException
.
Java language access control may be suppressed for a particular
reflected member by setting a flag using the
setAccessible
method, as explained below.
public
members
and constructors) of any class it may link against. By default,
application code that gains reflective access to a member or
constructor may only use the reflected member or
constructor with standard Java language access control.
The standard policy may be overridden by
calling the reflected member's setAccessible
method.
The ability to call the setAccessible
method is in
turn controlled by the suppressAccessChecks
target of
the permission ReflectPermission
.
There are two types of automatic data conversions. Wrapping conversions convert from values of primitive types to objects of class types. Unwrapping conversions convert objects of class types to values of primitive types. The rules for these conversions are defined in "Wrapping and Unwrapping Conversions."
Additionally, field access and method invocation permit widening conversions on primitive and reference types. These conversions are documented in The Java Language Specification, section 5, and are detailed in "Widening Conversions."
Field.get
or
Array.get
, or when it is returned by a method invoked
via Method.invoke
.
Similarly, an object value is automatically unwrapped when supplied as a parameter in a context that requires a value of a primitive type. These contexts are:
Field.set
, where the underlying field has a
primitive typeArray.set
, where the underlying array has a
primitive element typeMethod.invoke
or
Constructor.newInstance
, where the corresponding
formal parameter of the underlying method or constructor has a
primitive type A method that is declared void
returns the special reference null
when it is invoked
via Method.invoke
.
Widening conversions are performed at run-time:
Field
and Array
Field
and Array
Method.invoke
or
Constructor.newInstance
byte
to short
, int
,
long
, float
, or double
short
to int
, long
,
float
, or double
char
to int
, long
,
float
, or double
int
to long
, float
,
or double
long
to float
or
double
float
to double
.java.lang
named java.lang.reflect
. This
avoids compatibility problems caused by Java's default package
importation rules.
*As used on this web site, the terms "Java Virtual Machine" or "JVM" mean a virtual machine for the Java platform.